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1.0 Introduction 


This specification describes the Advanced SCSI Programmer's 
Interface for the MS-DOS environment. These specifications which 
were developed by Adaptec, have been proposed in conjunction with 
other major SCSI vendors, as the Common Access Method (or CAM) 
standard interface for SCSI. A similar standard interface is 
available for the OS/2 environment, which significantly minimizes 
the porting effort from MS-DOS. 


The biggest advantage of ASPI is that it supports concurrent 
operation of multiple devices through one SCSI interface. When you 
want to add support for a new type of SCSI device, you don't have to 
worry about the new device interfering with the devices that are 
already working in the system. 


Today, most SCSI interfaces are used for disk and tape only. 
Typically, the disk drivers directly manipulate the SCSI hardware. 
lf there is no low level SCSI manager such as ASPI, it is very 
difficult to add support for a new SCSI device since the new driver 
must interact directly with the existing drivers. Each time a new 
device is added to the system (CD-ROM, WORM drives, printers, 
network interfaces ...), the process is repeated and becomes 
increasingly complex. ASPI eliminates this problem. It is a device 
independent driver for the SCSI hardware. Device drivers talk to the 
ASPI interface interface and ASPI manages the SCSI hardware. ASPI 
encourages the use of many devices with SCSI. 


There is a growing list of ASPI compatible drivers for disk, 
tape, WORM, and CD-ROM devices available from Adaptec, third-party 
software companies, major OEM integrators, and peripheral 
manufacturers. 
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2.0 Accessing the SCSI Driver 


After the SCSI Driver loads in memory, other device drivers 
can access the SCSI Driver by: 


1. Opening the SCSI Driver 

2. Getting the Entry Point of the SCSI Driver 
3. Closing the SCSI Driver, if necessary 

4. Calling the SCSI Driver 


2.1 Opening the SCSI Driver 


Device drivers wishing to access the SCSI Driver must open 
the driver by performing a DOS function call OPEN A FILE as follows: 


Perform DOS Function call through INT 2th. 


On Entry: 
AH =3Dh 
DS:DX= pointer to ‘SCSIMGR$' 
AL <=0 
On Return: 
AX = File Handle if carry flag is not set, 


Error Code if carry flag is set 
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2.2 Getting the Entry Point of the SCSI Driver 


Device drivers can get the entry point to the SCSI Driver by 
performing a DOS function call JOCTL READ as follows: 


Perform DOS Function call through INT2th. 


On Entry: 
AH = 44h 
AL = 02h 
DS:DX = pointer to data returned 
CX = 4 
BX = File Handle 
On Return: 
AX = nothing 


Data returned is the entry point of the SCSI Driver. 
byte 0 : offset (lo) 
byte 1 : offset (hi) 
byte 2 : segment (lo) 
byte 3 : segment (hi) 
2.3 Closing the SCSI Driver 


Device drivers wishing to close the SCSI Driver must close the 
driver by performing a DOS funtion call CLOSE A FILE. 


Perform DOS Function call through INT 21th. 
On Entry: | 


AH = 3Eh 
BX = File Handle 


On Return: 


AX = Error Code if carry flag is set, 
NONE if carry flag is not set 
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2.4 Calling the SCSI Driver 


Device drivers must perform a FAR call to the SCSI Driver with 
the address of a SCSI Request Block on the stack. For example: 


PUSH 


FAR CALL 


@REQUEST BLOCK ‘Push 4 byte pointer to 
‘request block 
SPI ENTRY POINT ‘Issue FAR call to SPI 


‘entry point 


CD BS CD PEs DAD COED OE) D-DD ED CES EED GH ND ETD GD ED OD ESS es ee EES GE GE 





gé---=— 


Requesf Block Pointer (segmenf) 


PPR TRATED: LD RALLY EI: EDP ETY LS CRD CATES EG ETE EPO TEED EY EEE LD LEE TED E CALS A CBRE ROLE) CD AIDED CELE CM GEE EID ES 


Request Block Pointer (offset) 








Return Address (4 Byfes) 


ED-EVEP GHA GOED GEE CES Gee Ge Ge EO SE OSE B6S Grease Gen GPes Cea es ee IP EM CE Gn ee ee 
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3.1 The SCSI Request Block Header 


SPI request blocks are used by both drivers and applications to 
send commands to the SCSI driver layer. All request blocks have an 
eight block header. 


: 


DESCRIPTION 


Command Code 
Status 

Host Adapter Number 
Flags 

Reserved (OQ) 
Reserved (O00) 
Reserved (00) 
Reserved (00) 


NOOMBWNH —O 


3.1 SRB Command Codes 


DOTS EE ATED AE EED CEE EEE LEAL EEE TELE ED CLL LY CEL GR ALLY ARAL LY LA TILED AGI LLIN EELIOP LESLIE LGD LE LLE LE) ELODIE OLED OED ENE LDPE AD OLY AEE GE) CEB 


COMMAND CODE _ DESCRIPTION SECTION 
OOH Host Adapter Inquiry 3.2. | 
O1H Get Device Type 7 3.2.2 
Q2H Execute SCSI I/O command 3.2.3 
03H Abort SCSI 1/0 command 3.2.4 
O4H Reset SCSI Device 3.2.5 
OSH set Host Adapter Parameters 3.2.6 


SD FER ED Cae GORE Al GRA PEAT PE CED TALE ED ED GPA, ROE LEED PED ELT EL LI TELESIS LILLE B LED ED ELD CL ED GEOG AEE TP GERD ETE LEAS SEED SP SIPEG LSE GES IS EPDM IRE AY LONES EEE ED ED PE) 
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3.1.2 SRB Status Codes 


The status byte is used to post the status of the command. A 
zero status indicates that the request is still in progress or queued. 





STATUS CODE DESCRIPTION 


OOH SCSI request in progress 

O1IH SCSI request completed without error 
O2H SCSI request aborted by host 

O3H Unable to Abort SCSI request 

O4H SCSI request completed with error 
80H = Invalid SCSI request 

81H Invalid Host Adapter Number 

82H SCSI device not installed 


3.2.1 Host Adapter Inquiry 


BYTE DESCRIPTION 
0 Command Code = 0 
] Status 
2 Host Adapter Number 
3 Flags 


4-7 Reserved (00) 
8 # of Host Adapters 
9 Target Id of Host Adapter 
10-25 SCSI Manager ID 
26-41 Host Adapter ID 
42-5/ Host Adapter Unique Parameters 


Pe TS ED 





This command will always return non-zero status. A SCSI 
request complete without error status indicates that the remaining 
fields are valid. An invalid host adapter number status indicates 
that the specified host adapter is not installed. 
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This function is also used to get information on the installed 
host adapter hardware including the number of host adapters | 
installed. It can be issued once with host adapter zero specified, in 
order to get the number of host adapters. If further information is 
desired, the command can be issued for each individual host adapter. 


3.2.2 Get Device Type 


BYTE DESCRIPTION 
0 Command Code = | 
1 Status 
2 Host Adapter Number 
3 Flags 
4-7 Reserved (QQ) 
8 Target Id 
9 LUN 
10 


Peripheral Device Type of specified Target/LUN 
11-16 Reserved for Expansion 


This command will always return with non-zero status. A 
command complete without error status indicates that the specified 
device is installed and the peripheral device type field is valid. A 


SCSI device not installed error indicates that the peripheral device 
type field ts not valid. 
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3.2.3 Execute SCSI I/O Request 





BYTE DESCRIPTION 
QO | Command Code = 2 
1 | Status 
2 | Host Adapter Number 
3. | Flags (Direction,SCSI Linking and Posting) 
4-7 | Reserved (00) 
8 | Target Id 
9 | LUN 
10-13 | Data Allocation Length 
14 | Sense Allocation Length (N) 
15 | Data Buffer Pointer (offset lo) 
16 | Data Buffer Pointer (offset hi) 
7st Data Buffer Pointer (segment lo) 
18 | Data Buffer Pointer (Segment hi) 
9 | Link Pointer (offset lo) 
20 | Link Pointer (offset hi) 
21 | Link Pointer (segment lo) 
22 | Link Pointer (Segment hi) 
23 | SCSI CDB Length (M) 
24 | Host Adapter Status 
20 | Target Status 
26 | POST Routine Address (offset lo) 
2/ | POST Routine Address (offset hi) 
28 | POST Routine Address (segment lo) 
29 | POST Routine Address (segment hi) 
30-41 | Reserved for DOS Specific definition 
42-63 | Reserved for SCSI Manager Workspace 
63-(63+M) | SCSI Command Descriptor Block 
(63+M)- | Sense Allocation Area 
(63+M+N) 


This command will usually return with zero status 
indicating that the request was queued successfully. Command 
completion can be determined by polling for non-zero status or 
through the use of the POST routine field. 
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The FLAG Byte (byte 3) has four valid bits: 


Bit 4 - Outbound Data transfer (WRITE commands). 

Bit 3 - Inbound Data transfer (READ commands). 

Bit 1 - Link Pointer Address is valid, SCSI Linking is enabled. 
Bit 0 - POST Routine Addressis valid,POSTing is enabled. 


Note 1: Bit 1 must be set to enable SCSI Linking, and 
Bit O must be set to enable POSTing. 


Note 2: If bits 3 and 4 are zero, then the SCSI command will be 
executed, but data overrun and underrun errors may not 
be detected. 


Target ID and LUN fields are used to specify the peripheral 
device involved in the I/O. 


The data allocation length indicates the number of bytes to be 
transferred. The maximum data allocation length is 64k bytes. 


The request sense allocation length indicates (in bytes) the 
number of bytes allocated at the end of the SRB for sense data. 
Request sense is automatically generated if a check condition status 
is presented at the end of a SCSI command. 


The data buffer pointer field points to the data area for SCSI 
transfer. The data buffer pointer must be an even address. 


The link pointer field points to the next SRB, which contains the 
next SCSI link command. If Bit 1 of the flag byte is set, the SCSI 
Driver executes the next SRB in the link pointer field. Note that the 
linking feature is only for SCSI devices that support command 
linking. It is not intended for SRB linking. It is intended for SCSI 
command linking. 
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The SCSI command length is the length of the SCSI command 
descriptor block. 


The Host Adapter Status format is as follows: 


HA STATUS DESCRIPTION 
OOH No host adapter detected error 
WH Selection Timeout 
12H Data OverRun/UnderRun 
13H Unexpected Bus Free 
14H Target bus phase sequence failure 


15H - FFH Reserved 


The Target Status format is as follows: 


TARGET STATUS DESCRIPTION 
QOH No target Status 
02H Check Status (Sense Daia is in Sense Area) 
O8H Specified LUN Busy 
18H Reservation Conflict 


EAE CE ES AS ED ED ATES EO) ES SSE PED GE BOSE LD COIS PED EE EEE IDL LEED EY LPT GT I A LE LEO IT IE OLED SALLE) CED LAGNED GD LEY GEE LEE LGEALDD CRS LSID LED DY CELE) ELD ABTD CREATE, OLAS RADE EDS ETE) CRECTDy OD EID 


The POST routine address, if specified, is called when the I/O 
is complete. This occurs much like an interrupt to the calling 
driver/program, signaling that the I/O is complete. A POST routine 
address of zero indicates that POSTing is not necessary. 


On entry into the POST routine, the POST routine assumes that 
interrupts are enabled and the pointer to the SRB POSTed is on the 
stack. On return from the POST routine the SCSI Driver assumes 
interrupts are enabled. 
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The SCSI Driver performs a FAR CALL to the POST routine 
address and the POST routine performs a FAR RETURN when done. 


The SCSI command byte fields contain the SCSI Command 
Descriptor Block (CDB). The length of the SCSI CDB is specified 
in the SCSI command length field. 


The sense data area is filled with sense data on a check 
condition. The length of the sense data area is specified in the 
sense allocation length field. 


SCSI Manager workspace, bytes 30-63, are reserved by the SCSI 
Driver as long as the SRB status byte is zero. When 1{/O is complete 
and the SRB status byte is non-zero the workspace is no longer 
reserved and are don't care. 


ASPI Command Posting 


POSTING refers to the SCS! manager making a FAR call to a 
POST routine as specified in the SRB. The POST routine is called to 
indicate that the request 1/O is complete. The specific SRB 
completed is indicated by a 4 byte SRB pointer on the stack. The DS 
of the POST routine as specified in the SRB is also passed on the 
stack. The POST routine will be called with interrupts enabled. It is 
assumed that registers are preserved by the POST routine. When the 
POST routine is called the stack will be set up as follows: 


SRB Pointer (4 bytes) 


Return Address(4 bytes) 


Note: The stack grows downward. 
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ASPI SCSI Command Linking 


ASPI provides the ability to use SCSI linking to guarantee the 
sequential execution of several commands. Note that the use of this 
feature requires the involved target(s) to support SCSI linking. 


To use SCSI linking, a chain of SRBs is built, with the link 
pointer in the SRB used to link the elements together. The SCSI 
linking bit should be set in the SRB flags byte of all SRBs but the 
last in the chain. When a SCSI target returns LINKED COMMAND 
COMPLETE, the next SRB is immediately processed, and the 
appropriate CDB is dispatched. When using SCSI linking, check that 
the linking flags in the SCS! CDB agree with the SCSI LINKING flag in 
the flags byte. Inconsistencies can cause unpredictable results. For 
example, setting the SDB up for linking, but failing to set the SCSI 
LINKING flag may result in a random address being used for the next 
SRB pointer. Any error returned from the target on a linked 
command will break the chain. Note that if linking without tags is 
used as defined in SCSI, POSTING may not occur on any elements in 
the chain until the chain is complete. 
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3.2.4 Abort SCSI I/O Request 


This command is used to remove a waiting SCSI request from the 
queue. It should be issued on any 1/O request that has not completed 
if the driver wishes to timeout on that request. If the specified 
request is not found in the queue, the abort will fail. This command 
is not currently implemented. 


BYTE DESCRIPTION 
0 | Command Code = 3 
1 Status 
2 | Host Adapter Number 
3 | Flags 
4-7 | Reserved (00) 
8-9 | SRB Pointer to Abort (offset) 
10-11 | SRB Pointer to Abort (segment) 


Note: Status in the SRB header will be as follows: 





02H - SCSI request aborted by host 
03H - Unable to abort SCSI request 
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3.2.5 Reset SCSI Device 


This command is used to reset a specific SCSI target. This 
should not be of use in normal operation, but if the I/O to a 
particular device hangs up for some reason, drivers can abort the I/O 
and reset the device before trying again. 


BYTE 


Command Code = 4 


DESCRIPTION 


Status 

Host Adapter Number 

Flags 

Reserved (00) 

Target Id 

LUN 

Reserved for SCSI Manager Workspace 
Host Status 

Target Status 

Reserved for SCSI Manager Workspace 


3.2.6 Set Host Adapter Parameters 


This command is set aside for programmers to setup vendor 
unique features of a specific host adapter. 


DESCRIPTION 
Command Code = 5 
Status 
Host Adapter Number 
Flags 


Reserved (OO) 
Vendor Unique 


0 Re ED OR EE OR ED ED EN EE SE ED ED OED OED. CD. ED OD ED COE 68 8B 8 OE DR ED 8 ES 8 0 8 ED 8 8 8 8 EE 8 8 OF 60 8 ED OF EEE 08 8.08 0S 01 ORO OOOO 


© 1989 Adaptec, Inc. 15 


